grokking koreader
i have sung the praises about the Kobo Libra 2 since purchasing it almost two years ago, shortly after its release—replacing my Kindle Oasis as my daily driver for consuming digital content.
Both ereaders use a 7” eink display but it is Rakuten’s Nickel software that elevates the Kobo past the Kindle IMO—its intuitive UX, more granular control of page layout and font control, and Calibre integration vastly distancing itself from its Kindle competition (for those interested in more than simply being served up books from Amazon’s store).
As someone obsessed with typography and readability—if not apparent from this site’s obsession with mono-dyslexic fonts—kobopatches completed the refinement of the Kobo Nickle UX for me. Until..
TL;DR Kobo Nickel provides a very polished ereader UX. For the ultimate control of econtent on the Kobo, however, KOReader can handle publisher corner cases that elude even kobopatches’ capabilities whilst providing more connectivity options and gesture controls to create an even mone fluid ereading experience—or depending on one’s point of view, deeper, if one savours delving into reading progress statistics and charts.
UPDATE: to gesture assignments (as personal reading habits dictate).
fast forward
and today i am firmly in the KOReader camp now. KOReader is often only cited for PDF content consumption on the Kobo—improving upon Kobo’s inbuilt PDF viewer—because its price of entry (learning curve, due not so much to difficulty as to breadth) seems unwarranted given Kobo Nickel’s already robust and intuitive UX.
What prompted this change was time (on my hands), Calibre integration with KOReader and the desire to add swipe control of the warm light (in addition to the stock front light control)—swipe control of the backlighting being a killer feature of the Kobo IMO, finding the automatic brightness control of the Kindle Oasis unusable. Time would later reveal a plethora of publishing control tweaks for the odd ebook which defied my preferred layout theme settings.
All it took was giving myself a day to wrap my head around KOReader’s organization. Yes, it took me a day to grok KOReader—to become familiar with the nested organization of menus to set the global defaults to achieve the “look” and workflow i desired. What took a lot of time going back and forth through menus until i had everything set up the way i wanted—with more refinement to be made, no doubt, as i log in the reading hours—has now produced an ereader UX that is ultimately transparent in use and even more streamlined than Kobo Nickel, nimbler (with Calibre too) and more powerful.
why
For the casual ereader user, this sort of investment is probably too steep to warrant the effort. But there is an audience for which KOReader can enhance both the delivery and consumption of digital content. In short, anyone reading this far might do well to consider KOReader, especially if you, like me, enjoy multiple books in your reading rotation.
This write-up’s length is not intended to emphasize KOReader’s complexity—it just sort of grew (as i returned to update it)—but it is easy to see how its breadth would test the impatient (myself included). As i hadn’t come across any single source covering a KOReader configuration use case, i figured i would do well just for my own reference—much of the length simply being tabular descriptions of the various settings that, once configured, produce an ereader transparent for my use case.
This document will be a useful reference (for me) for any future KOReader updates/installs.
the top menu system
after KOReader is installed and first launched from NickelMenu a quick guide will be presented illustrating the basic functionality of the app. Opening the file browser and selecting a book is straightforward enough but delving into the menu system to utilize KOReader’s full potential is daunting—mainly because, unlike the stock UI of a Kindle or even a Kobo, KOReader’s breadth is exhaustive.
What this requires is patience and a willingness to familiarize oneself with its menu structure—and not be distracted by all the functionality and extended capabilities it provides. It is laid out logically enough—just overwhelming in its granularity—the topmost icons (when opened while reading a document**) covering..
- current document**
- document settings**
- KOReader settings
- tools
- search settings
- file browser
- system
**The document related menus only show if the menu system is accessed from within a document. Logical but initially confusing until one is familiar with KOReader’s context oriented functionality.
Getting used to KOReader’s menu organization is key. It is the depth of these menu lists that challenges familiarity. If not for gestures, navigating KOReader would otherwise be repetitively painful but if one is willing to persist and slowly set KOReader up, it can become even more streamlined in operation than the much more limited Kindle or even stock Kobo device.
theme profiles
one of the features i missed on the Kobo was Kindle’s themes—document layout templates that could be applied to a document on the fly to change various fonts/size/contrast, header/footer content and margins/line spacing. Useful for switching between favourite setups for varying content.
From the bottom menu the document’s layout can be set..
- orientation
- margins
- rendering (line spacing)
- font size/spacing***
- font contrast (weight/kerning)
- publisher settings/optimizations
***The font typeface is selected from the top menu document settings. Custom fonts sideloaded to the Kobo fonts folder are available.
KOReader returns user themes to the Kobo platform. After tweaking the bottom menu font/layout settings, from the top menu tools, the current settings may be saved as named themes—useful for switching the “look” of a document simply by applying (“executing”) a theme.
global defaults
for many of the settings may be set with a long press of the menu item setting. These settings are applied to any newly opened document—each document retaining its own settings and adjustments separate from others on subsequent opens. This is a hugely useful persistent state when one has many books in one’s reading rotation.
As someone who has a particular “look” (font, margins, etc.) applied to all reading material, global defaults generally format the document as desired. When needed, top menu document settings may be applied to override publisher settings to “force” the desired look.
There are simple overrides for font sizes and line heights, as well as the ability to apply custom epub CSS formatting for even finer control—i have only had to resort to the simple overrides when the need arises. These simple overrides are a godsend for the pixel peeper, sparing much time that otherwise would be spent tweaking the font and line spacing to override publisher settings to match one’s default theme settings.
gestures
the left side Kobo brightness swipe control is one of my favourite features of the Libra 2. i was always curious why Rakuten did not implement a right sideswipe feature for controlling the warm light. Seemed logical to me.
Luckily, by default, KOReader adds warm light control just as one would expect. To those defaults i have added..
one finger swipe (dialogues - actions)..
| swipe from | left corner | right corner |
|---|---|---|
| Top | Table of Contents | Metadata search |
| Side (swipe up/down) | Warmlight control | Backlight control |
| Bottom | Open vocabulary builder | Back to previous location |
| Diagonal swipe | Screen refresh | Screen refresh |
The KOReader defaults for left/right side up/down swipe to adjust the frontlight/warmlight intensity have been kept—logical, convenient and one of the compelling reasons for using KOReader (in Kobo’s case for the warmlight control and in jailbroken Kindle’s for both). Similarly, the diagonal swipe across the screen in any direction to (default) refresh the screen of any ghosting artefacts has also been kept—a very handy shortcut (though, i will say that KOReader appears less prone to ghosting than the stock Nickel firmware).
All gestures can be configured/overwritten as one pleases to suit one’s use case—and easily tuned to meet one’s workflow. Gestures i have currently set (subject to change :)..
tap corner (actions)..
| side | left | right |
|---|---|---|
| Top | Toggle night mode | Toggle bookmark (KOReader default) |
| Bottom | Show frontlight dialogue | Set portait layout settings |
****Finger pinching/spreading allow on the fly (default) font resizing—useful for in book font changes. Restoring the default font size is much less frustrating to do with taps than the reverse finger action :) Note that multiple actions may be triggered by a single gesture.
long press on corners (dialogues)..
| side | left | right |
|---|---|---|
| Top | Book map | Bookmarks |
| Bottom | Toggle frontlight | History |
Kobo implemented quick access to the last three books opened for multi-book readers. With one press into my book history, i can cycle through my usual rotation of three dozen books with just three finger presses (two if i didn’t read so many books at a time! :) Similarly, i can search for a book from my current book with just one finger swipe (see one finger swipe—it doesn’t get more streamlined than this.
two finger tap corner (dialogues / actions)..
| location | left | right |
|---|---|---|
| Top | Pass through | Restart KOReader |
| Bottom | Pass through | Reboot device |
i happen to prefer taps and presses versus finger swipes but there are many gesture methods available—double tap, two finger swipe, spread and pinch and multi-swipe. For power users with better memories and more complex use cases, one could probably eliminate navigating the menu system altogether!
NOTE: these assignments were previously double tap gestures but i found the timing somewhat tricky to get used to—the timing interval is user definable—often inadvertently triggering the single tap corner action instead. That said, the general population may find the default (or custom) interval settings work perfectly for them :)
double tap (dialogues / actions)..
| location | left | right |
|---|---|---|
| Top | Skim document | Start USB storage |
| Side | Toggle page turn direction | Toggle page turn direction |
| Bottom | Turn off Wi-Fi | Set landscape layout settings |
Gesture shortcuts are absolute game changers. No more messing with multiple taps to start the next book, clear eink ghosting, etc. This available nimbleness just adds immeasurable delight to the e-reading experience and, ironically, hides the initial impediment of KOReader’s deep menu system.
NOTE: double tap gestures must be “enabled” from the settings -> taps and gestures menu.
dictionaries
are not by default installed so must be downloaded. A number of common stardict formatted dictionaries are available from KOReader’s top menu search for downloading.
While this may seem a step back from the Kindle and Kobo built-in dictionaries, it is in fact a boon. KOReader’s dictionary handling is superlative—allowing not only multiple dictionaries to be easily added (and side loaded) but displaying the search results across multiple dictionaries (versus the single dictionary allowance of the native ereaders). Useful for concurrent language handling and etymology buffs!
Furthermore, highlight searches of words within the dictionary search results allow endless lexical exploration.
status bars
KOReader provides extensive customization of the top and bottom status bars. They can be filled with numerous data fields (and disabled altogether) but i prefer a more minimalist look..
top bar (left / right)..
- author and book title
- time
- book page count
- battery
- progress bar with chapter ticks
bottom bar (centered)..
- chapter pages left
- wifi icon (displayed only if connected)
- chapter title
A customizable progress bar can be presented in the bottom status bar instead—i prefer the top bar’s pencil thin marker.
While the informational content i have chosen may look like a lot, it is, in fact, only a small selection of the information elements available. As minimalistic as what i had set up under Kobo Nickel/Clock but with a more reductionist presentation.
user customization
as KOReader is written in lua script, one may further customize its behaviour by modifying its installed source code. While this may sound daunting, pretty much the worst one can do is render KOReader inoperable, requiring a hard reboot into Nickel and reinstall of the application (though, i have not attempted to bork my device this way!).
To date i have changed (from the .apps/koreader/frontend directory)..
- both buttons to act as page forward in portrait orientation (independent of button side). This is a feature of kobopatches to the Nickel UX that i have become fond of for flexible single-handed ereader operation (preferring to use a screen tap for the rare occasion to page back)
| source file | function | line edit |
|---|---|---|
| device/input.lua | Input:init | UPRIGHT RPgBack = “RPgFwd” UPSIDE_DOWN RPgFwd = “RPgFwd” |
- the highlight display duration of words—from 0.5 to 1.5 seconds—after the dictionary window (which often covers the word) is closed to relax the time available to spot my last reading position on the page
| source file | function | line edit |
|---|---|---|
| ui/widget/ dictquicklookup.lua |
DictQuickLookup:onClose | scheduleIn() 1.5 |
- change status bar “no separator” to double space for a more relaxed visual separation of information elements (versus distracting separator glyphs :)
| source file | function | line edit |
|---|---|---|
| apps/reader/modules/ readerfooter.lua |
ReaderFooter:get_separator_symbol | return “ ” |
- lower font size range minimum from 12pt to 11pt
- increase line height range maximum from 200% to 300%
| source file | function | line edit |
|---|---|---|
| apps/reader/modules/ readerfont.lua |
ReaderFont:onSetFontSize ReaderFont:onSetLineSpace |
new_size 11 min() 300 |
As can be seen, i tend to tweak around the extremes—small font sizes with a touch of extra line spacing. My initial defaults started at 12.5pt font size with 200% line spacing—exhibit above—but has since been tweaked to 11.5pt at 205% for monospaced dyslexic fonts (for ease of highlighting).
Note: Editing the settings.reader.lua or profiles.lua file directly is an alternate way (and simpler for a single set of fixed values)—to set global/profile defaults outside the default ranges (which will persist as long as the settings are not subsequently altered via the bottom menu and saved as theme and/or set as global defaults).
Update: Line height from the above image has since been increased to 210% to further ease eye movement to the beginning of the next line (from the end of the previous). It is a highly personal setting but having been focused on typeface readability and reading effort, noticed a reduction in line hunting (which may be purely be an age related issue :)
This is just a sample of what can be done to tailor one’s ereading experience—thanks to the responsive KOReader community i was able to dig under the hood and locate the relevant lua scripts to modify. These changes only required editing a few lines of code with a text editor.
Note: These changes will require re-applying if/when KOReader is updated on the device—the application scripts being subsequently overwritten. There is a mechanism to apply “user” patches from a “patches” folder—which is not affected—but i have not yet invested the time clone to the relevant lines of code into functions for such a purpose. Regardless, for the few lines changed, it is still much less effort than the previous maintenance cycle required with my kobopatches customizations and each Kobo firmware update cycle.
history
the history view lists books that have been opened for reading. i remove books from the list on completion—a simple long press on the entry to pull up its action menu is all it takes—yielding a list of books in my reading rotation.
Whereas Kobo Nickel has a drop down of your last three books opened, i now with a swipe gesture can access my rotation of dozens of ebooks. It is a rotating list, the last book opened appearing at the top of the list. A single tap takes me to the last page of my list and i am good to go to select my next book. Easy peasy but bears mentioning for those who read multiple books or switch between multiple references.
Again, an example of how you can integrate the various views into your particular reading workflow.
calibre
When KOReader is first launched, books are accessed via the file browser by filename. But books sideloaded via Calibre can be accessed via their Metadata—by author, title, series and collections (tags).
Under Nickel the Calibre plugin KoboUtilities syncs the metadata and reading progress (if set up) automatically—the downside being the reading progress data taking a minute or so of time to upload if one’s on device catalogue is large (every book being scanned over usb). With KOReader, syncing is much faster due to reading progress stats of only “opened” unfinished books needing to be manually resynced.
Newly added books under Nickel are automatically added to Nickel’s UI—books, authors, series and collections—upon usb disconnect from Calibre*****. With KOReader, however, the Calibre database on the device must be updated after adding/updating books/metadate from Calibre’s device/update cached metadata action—KOReader access to the metadata must be setup once, via the top menu tools/calibre/search/manage/scan action.
The Calibre plugin KOReader Sync must be manually triggered to transfer the reading progress stats to Calibre’s database. There is a sync to the device—which i have not had need to test as of yet (waiting for the next gen Kobo Sage to be released where the library will be copied to :)
*****If books are added from Calibre from KOReader’s usb connection, Nickel’s catalogue must be manually updated via the books/import action—just to keep it synchronized (otherwise, the side loaded books, while visible to KOReader, will not show as having been sideloaded to the device the next time Calibre is launched).
screensaver
there are many different types of screensavers available to KOReader—book covers, image files, reading statistics..
But it stands worth pointing out one hugely beneficial and easily configured setting..
- personalized screensaver message
This allows you to place contact information on your screensaver should your precious device ever be lost, heaven forbid! Why this is not available on every ereader (not to mention portable electronic) device is puzzling. Just one more way KOReader focuses on the user.
Note: Nickel allows custom screensaver images placed in its screensaver folder—KOReader has its own screensaver folder. KOReader’s custom screensaver message is a great timesaver but i highly recommend one edit a screensaver image with contact information for Nickel so this image is available upon device reboot.
stability
Kobo users have reported on occasion, random device freezes/reboots with the Nickel UI related to sideloaded epub content. i have experienced this as well with some firmware releases seeming to be more stable than others—this has always been difficult to ascertain with ever changing epub/kepub reading material.
KOReader’s epub engine appears to be much more robust and immune to internal ebook CSS violations. Rock solid in fact. While only weeks since installation, i have not experienced a single hiccup with the software—and that is reading 3 to 5 hours daily with a rotation of 30 ebooks.
The added benefit is no longer needing to convert epubs to kepubs to obtain advanced ebook statistics (under Kobo Nickel)—keeping on device file sizes to a minimum and saving computer conversion time. Win win all around.
android
anticipating Ratta Supernote adding KOReader to their Android enote platform (at some point), i installed KOReader onto my Pixel 7 Android phone..
Custom fonts, dictionaries.. everything worked as expected. The customizations described for the Kobo are a bit more involved for the Android platform—the APK file needs to be unpacked (unzip), the appropriate files edited or added, then the directory tree repacked and the resultant APK installed.
i did this stock install and layout setup just to see how KOReader would look, and it looked exactly as expected. i did not attempt to implement my source code customizations simply because i would not personally use my phone for reading—despite its form factor, the smartphone with Corning Glass, metal body and protective case weighs significantly more than my Kobo Libra 2 ereader making single handed usage more awkward and less ergonomic. YMMV. But it can be done!
There are eink devices with this form factor but they currently cost significantly more than even the Kobo Sage (which also can be used as an enote device) so only meet a very specific use case. Now, if Rakuten were to issue a Kobo ereader in this form factor with better ergonomics and priced accordingly within their product offerings.. :)
early closing thoughts
After just a few weeks i can honestly say KOReader has elevated my ereading enjoyment beyond my wildest dreams. And this off-the-cuff write-up only scratches the surface of what is possible with KOReader. i have not touched upon the various views KOReader provides into reading progress statistics, document skimming, vocabulary review, bookmarks, epub CSS formatting, connectivity features (wireless Calibre, news feeds, ssh), etc. i doubt very much there is any feature missing for even the most hard core reader (though, obviously, ongoing development reflects ever expanding user functionality and refinement).
The beauty of the application is that one only needs to start using it—as initially daunting as it may be—and gradually discover the useful power one simply never had available on any other stock ereader.
And then there is the dev community and the frequent updates to refine and optimize the application—i can’t say enough about how “open” this software truly is. If you’ve ever thought that the promise of eink was in becoming your own epublisher—consuming econtent to your own layout design preferences and UX—then KOReader just may fit your bill.
i highly recommend it.
kindle oasis
since the initial draft of this post, i was able to jailbreak my Kindle Oasis—if one can avoid updating their recent Kindle’s firmware, eventually means are published to jailbreak the device before Amazon pushes out yet another firmware update patching such a security hole. It is an involved but straight forward process and, for anyone wishing more control over the UI, well worth the effort (although, one does give up direct device integration to their Amazon account).
KOReader functionality for Kindle hardware is slowly getting there. It is not as well integrated as on Kobo devices—for example, USB access requires exiting KOReader altogether and gesture control of the backlight/warmlight feels less responsive. (i am uncertain about some of the more “advanced” features of KOReader as the Kobo Libra is my primary ereader).
Launching KOReader on the Kindle requires navigating to the “Library” and opening (launching) the KUAL document. From there, one selects the “KOReader” and, voila, you now can enjoy the best ereading software.
The folder structure of KOReader remains identical, so fonts and patches can be applied similarly.